package com.srmt.common.ratelimit;

/**
 * 限流器抽象接口
 * 支持本地限流和分布式限流的统一抽象
 * 
 * @author SRMT Development Team
 * @since 1.0.0
 */
public interface RateLimiter {
    
    /**
     * 尝试获取令牌
     * 
     * @param api API端点标识
     * @param timeout 最大等待时间(毫秒)，0表示不等待，立即返回
     * @return 获取成功返回true，失败返回false
     */
    boolean tryAcquire(String api, long timeout);
    
    /**
     * 尝试立即获取令牌，不等待
     * 
     * @param api API端点标识
     * @return 获取成功返回true，失败返回false
     */
    default boolean tryAcquire(String api) {
        return tryAcquire(api, 0);
    }
    
    /**
     * 获取令牌，如果无法立即获取则阻塞等待
     * 
     * @param api API端点标识
     * @throws InterruptedException 如果等待被中断
     */
    void acquire(String api) throws InterruptedException;
    
    /**
     * 设置API的QPS限制
     * 
     * @param api API端点标识
     * @param qps 每秒请求数限制
     */
    void setQps(String api, int qps);
    
    /**
     * 获取API的QPS限制
     * 
     * @param api API端点标识
     * @return QPS限制值
     */
    int getQps(String api);
    
    /**
     * 获取当前可用令牌数
     * 
     * @param api API端点标识
     * @return 可用令牌数
     */
    int getAvailablePermits(String api);
    
    /**
     * 重置限流器状态
     * 
     * @param api API端点标识，如果为null则重置所有API
     */
    void reset(String api);
    
    /**
     * 关闭限流器，释放资源
     */
    void shutdown();
}